Slurpee.txt
6/6/94

Slurpee 1.0
transfers paragraphs or tab-delimited text
between a text file and Newton soup entries
via a terminal emulator and serial connection

Keywords: data and text transfer, soup utility, terminal emulator, freeware


=====
Why?

I wanted a convenient way to move information from the desktop to soups on the
Newton, especially text paragraphs to separate Notepad entries, and vice
versa.  Newton Connection Kit (NCK) is also a possibility, though it is
slower, more complicated, and expensive.  Although Slurpee was created
primarily to support moving NewtonScript application/method sources by users
of my Newt application development tool, I thought that this utility may be
useful for others as well.


=====
Slurp and Slurpee -- Introduction and Differences

Slurpee is a customized version of the Apple DTS "Slurp-3" example -- with
thanks to the original author Scott (Zz) Zimmerman. The original Slurp
documentation and examples are included as SlurpOld.txt and CasioNam.tab. I
did not include the Slurp NTK project source files -- these can be obtained
from AppleLink and ftp.apple.com.

Slurp: Copyright 1993, 1994, Apple Computer, All Rights Reserved.
Slurpee modifications: Copyright 1994, S. Weyer

Slurpee is freeware (especially since so much of it is based on Slurp). Slurpee
may be freely distributed via online services and bulletin boards if it is
unmodified and includes this and other files mentioned here.  It may not be
commercially bundled or redistributed on CD-ROM, floppy disk, PCMCIA, networks
or other media without permission.

With enough encouragement, I may fix problems and add additional features. Of
course, you can also start with the original Slurp and roll your own version.
If Slurpee is useful to you, you can send email or a postcard, or better yet,
you can express your appreciation by registering for "Newt". Newt is a
shareware native Newton application development environment, i.e., you can
build applications in NewtonScript on your Newton.  More info at end of this
file.

The original Slurp is one-way: it transmits lines in a desktop tab-delimited
text file sent over a serial connection into Newton soup entries. Slurpee is
two-way: it can also send Newton soup entries as a tab-delimited text file.
(This combines functionality you'd find in the DTS SerialPro example and the
freeware Pour utility).  Slurpee also works both ways in converting between
multiline text paragraphs and entries in the Notes soup.  I think I've fixed a
few Slurp problems with disconnecting cleanly.  I also added a "para" datatype
that's useful for adding a note to a Names entry.

The original minimalist Slurp interface has changed only in the title, and some
additional status messages.  What's transferred and in which format is
controlled on the desktop side. For example, to send data to your Newton, you
tell Slurpee to Receive, and then send text containing soup name, format
specification, and data, via your terminal emulator, usually as a file.  To
send data from your Newton, you also set Slurpee to Receive; however, the text
file you send contains a soup name and format specification, but no data --
just a Dump command (this assumes you set up a log file to capture the data
returned).  Directions on how to setup Slurp/Slurpee with a terminal emulator
can be found in the original SlurpOld.txt and later in this file.

Warning: since Slurpee can add or remove entries from your soups, please keep
your information backed up, and follow the formats and commands carefully.

=====
Slurpee Uses

Here is a summary of the four kinds of transfer supported by Slurpee:
      direction                         soup
----------------------      -------------------------
from desktop to Newton      1. any soup      2. Notes
from Newton to desktop      3. any soup      4. Notes

=====
1. the original Slurp ("Slurp classic")
first line    soup name, e.g., Names
second line   frame specification, e.g., see SlurpOld.txt and CasioNam.tab 
other lines   each tab-delimited line corresponds to an entry
last line     BYE!

note: this only works with existing soups. Slurp/Slurpee does not create new
soups (currently).

For Names, I've found that a phones field is required, otherwise the entries
will generate errors later when you browse them.  At a minimum, you need
something like phones: ["workPhone"] in your framespec, then an extra tab in
your data entries to reflect an empty field.

If you'd like to add a text note to a Names entry (the text field you see when
you Show:Card&Notes), include notes: ["para"] in the frame spec. In the data
entries, the text in this position up to the next tab (or end of line if it's
last) will be included as a single paragraph in the note field.

=====
2. Slurp for Notes
first line    Notes
second line   frame specification, e.g., {labels: 'Business}**
line1 text
line2 more text
-----         paragraph delimiter (at least 5 dashes)
more lines
-----
BYE!

**the frame specification in 1) is more of a template with type information;
for Notes, it is used to provide default values.  Currently, only labels is
supported: the value is a symbol corresponding to a folder destination, e.g.,
'Personal, 'Business, or nil (for Unfiled).  In the future, other slots might
be supported like font, etc.  e.g., see Business.txt

Note: if you include a value for labels slot that does not (yet) exist, be sure
to do Edit Folders later on your Newton to add it -- otherwise, the only
way you'll see these entries is via All Notes.

Erase command:  if you know what you are doing (and have backed things up
first), you can insert an ERASE! command as the third line for 1&2.  This
erases all entries from the specified soup, or if you've specified labels in
your frame spec (for Names or Notes), it erases just the entries in that
folder.  This can be handy especially if want to get rid of many existing
entries before adding new information.  Warning: this does not give you a
dialog box asking to Confirm erasing of entries!!!  For example, if you edited
Newt sources for your project on the desktop, and wanted to replace these
completely on your Newton, you could do something like:

Notes
{labels: 'Programming}
ERASE!
createApp
func()
...
-----
addFields
func()
....
-----
BYE!


=====
3. Slurp in reverse
first line    soup name, e.g., Names
second line   frame specification, e.g., CasioNam.dmp
DUMP!

same powerful frame specification as in 1). entries are written to terminal
emulator as tab-delimited lines in frame specification order.  after the Dump
command is encountered, Slurpee pauses 10 seconds before transmitting data so
that you have a little bit of time to set up a log/capture file.  Any data
fields with text values that contain newlines will be transmitted as is (you
may need to re-edit results into a true tab-delimited text format).

=====
4. Slurp for Notes, in reverse
first line    Notes
second line   frame specification, e.g., {labels: 'Business}**
DUMP!

**this is used as a filter to copy entries from only that folder. it copies
just the first data entry from each Note (if it is non-empty text) as a
paragraph. for example, see Business.dmp
entries are written as multi-line entries separated by -----
same 10 second pause before transmitting


=====
How to Use (see SlurpOld.txt for further info):

- Download Slurpee to your Newton.

- Serial cable (still) connected to the Newton, with no other open serial
  connections on the desktop side (e.g., NTK inspector), or any other
  current use of comms on the Newton (e.g., beaming).

- Open a communications program (e.g., terminal emulator) on your desktop
  system, with the following specs:
    Serial Tool, 9600 baud, 8 data bits, 1 stop bit, XON/XOFF handshaking

  - For file transfer, specify the Text Tool.

- Open Slurpee and tap the "Receive..." button.  

- On the Mac/PC, choose "Send File..." in the comm program, and choose the
  file to be sent.  If you are doing a "Dump", immediately setup a file to
  log/receive/capture the result.  Slurpee will display the number of entries
  received/dumped in a view near the top of the screen.  When the file
  transfer is complete, Slurpee will automatically disconnect.


=====
Slurpee Change History

1.0
-----
- initial public release
- added 10 second delay after a DUMP! to allow time to log/receive/capture a file
- added an ERASE! command to clear out all soup entries or just those in a folder
- added a "para" datatype (useful for adding a note to a Names card)
- disconnects more cleanly

0.1
-----
- alpha/beta releases to Newt users


=====
Author

Stephen Weyer
17 Timber Knoll Drive
Washington Crossing, PA 18977-1052
Internet: weyer@guest.apple.com
America Online/eWorld/NewtonMail: SteveWeyer
AppleLink: WEYER.S


=====
Info about Newt

Newt 2.2 (aka Newt Turtle):
a native environment for developing simple applications using NewtonScript,
and for creating graphics using gestures, buttons, and NS.

Keywords: object-oriented programming, application development environment,
NewtonScript, NTK, learning, graphics, mathematics, Logo.

newt-devenv-22.sit / .hqx is usually found on:
  internet: newton.uiowa.edu:pub/newton/software/app/
            sumex-aim.stanford.edu(&mirror sites):info-mac/newton/app/
  newsgroups: comp.binaries.newton
  America Online(AOL): PDA:New Files (or PDA:Software Libraries:Newton)
  Compuserve: GO NEWTON (DL 8)
  AppleLink: Newton:Newton User Discussions:Freeware, Shareware and Demos
  eWorld: ???
  
Newt is shareware ($30 before 8/1/94) -- registered users receive a manual
describing additional features and NewtonScript syntax, along with source
examples -- of particular interest may be the Slurpee application itself in
Slurpee format for Newt. See NewtNews.txt for further info.

Also see RUNewt (aka Run,Newt,Run) -- an application for running, beaming and
mailing applications created by Newt 2.2. [runewt-22.sit / .hqx]